Netware Super Library/Netware Super Library.iso/inet_tcp/fxuuci/tech.doc

Text File | 1994-09-25 | 13KB | 283 lines

TECHNICAL GUIDE to FX Uucico                                 version 1.0
FX UUCICO is Copyright (c) 1993, 1994 by Jorge Cwik. All rights reserved.
<[e-mail]>

This documentation describes topics for advanced users and programmers
wanting to implement custom interfaces with FX Uucico. We are constantly
updating this notes acoording to quieres we receive. Check our server for
for the lastest update. ('help' to [e-mail])


              I.     NETWORKING
              II.    MULTITASKING
              III.   16550A FIFO UARTS
              IV.    TELEBIT modems
              V.     EXIT LEVELS
              VI.    STATUS files
              VII.   SECURITY
              VIII.  LIMITS AND MEMORY USAGE
              IX.    CUSTOM INTERFACES WITH FX UUCICO


I.     NETWORKING

FX Uucico is fully networkable, you can run multiple uucicos concurrently
over a network, without any kind of conflict between them. FX will manage
all contention automatically.

From FX point of view, networking means 'sharing', running multiple Uucicos
in the same file system. Running it over a network doesn't neccessarily
implies sharing if used in single user mode. Multitasking two or more
Uucicos on the same machine has the same sharing effect as a network. You
usually need to load SHARE under DOS and peer to peer networks, but it is
normally not needed in Netware and other Client/Serves NOSes. It is always
implicitely loaded in WinNT and OS/2.

All configuration files are accessed in shared mode, which means that you
don't need to make them 'read only'. Writable files and jobs are accessed
in exclusive mode. Note that other Waffle's uucp utilities are not 'share'
aware, and can be networked in a limited fashion only. Configuration files
accessed by them should still be 'read only' (static, systems, paths, etc).

Receiving *.X files are written in a temporay file, they are renamed only
after they are complete. This will prevent UUXQT from trying to execute
commands before they are ready. The 'debug' and 'uucico' logs aren't any
more appended with the channel parameter. FX writes a different log per
session and later append it to the main file. Host are locked during the
connection, locked host are skipped by concurrent polls. An incoming call
to a locked system will be rejected as per uucp standard.

FX uucico doesn't need different channel parameters. It still uses it as
a flag to enable its sharing features, When 'channel' is not found in the
'static' file, FX will optimize performance for standard operation. At this
release, the optimization is done in two points: *.X files aren't saved with
a temporary name, and logs are written directly to the main file. Note that
the actual content of the 'channel' parameter is not used at all, it may be
blank. Other Waffle's program do need channels. The 'fx.share' configuration
option can be used to override sharing, independently of channel.

If you multitask more than one Uucico in the same machine, you must take
care that they do not try to access the same port at the same time. FX
doesn't currently lock ports.


II.    MULTITASKING

By default, the software releases its time-slice when idle. The method
used is compatible with DesqView, Windows, OS/2, WinNT, and others.

Releasing time-slice will help other multitasking software. It could be
very important when running multiple FX copies concurrently. Specially
if some drive a low speed and others a high speed connection.

It is normally not a good idea to let the operating system controlling
FX time-slices. Specifically we recommend to NOT enable the "detect idle
time" under Windows.

You may disable FX time-slice releasing with the option 'fx.multitask'.

Some multitaskers will automatically return control to a program receiving
a hardware interrupt. In our case, an incoming byte from the serial port
would wake-up FX task immediately. But some others fail to do this context
switch, in those cases you may get better results by disabling fx.multitask.


III.   16550A FIFO UARTS

The -z switch controls the internal driver buffering for the FIFO. The
syntax is -z<bytes>, where bytes is the trigger setting in the uart. To
disable the FIFO uart entirely use -z0. Using any other value, will bypass
FIFO autodetecion, FX will _force_ the internal driver to enter FIFO mode.
This may be helpful for not fully compatible UARTS and in some virtual
environments.

In some multitasking/networking environments, using the full FIFO buffers
at high DTE speed may produce data loss. If you experiment 'Rx' errors
with the FIFO in full mode, you may 'trigger' interrupts with FIFO buffers
partially full. Using -z1 (which is not the same as -z0) will give the
maximum reliabiity to the system.

Most setups don't need to mess with this parameter at all. It is used by
the internal driver only, and disregared in FOSSIL mode.


IV.    TELEBIT modems

TELEBIT are very powerful modems very popular in UUCP hosts. 'Wordlblazer',
the latest model at this moment, is an excellent choice. If both sides are
using FX UUCICO you would be foolish not to use the 'y' protocol, you would
get unbelievable throughput. We reached 2670 cps in compressed news between
two 'Wordblazers'.

Otherwise, you must use 64 bytes packet size to activate the modem 'spoofing'.
Without the spoofing these modems are very slow. The TELEBITs modem will not
spoof if _any_ of both sides requests packets size that are not 64 bytes.
Window size doesn't matter.

In long delay lines (like international calls), it may be better to do one of
these:

   To transmit ascii non-compressed files, use protocol 'f'. If the other side
   supports it, use 4Kb packet; the modems will not spoof, but you may get bet-
   ter performance. If the quality of the line is good, try to connect in V32b
   ('Worldblazers' only).

NOTE:

   The latest Telebit ROMs implement an "enhanced spoofing", which
   spoofs large packets and windows 7. FX fully supports this new
   enhanced spoofing in any packet size and windows combination.


V.     EXIT LEVELS

If 'fx.wQuirks' is on, FX Uucico returns 0 when one or more connections
were successfull, otherwise returns 1. Successfull means that the uucp
handshake has been acomplished. These values can be overriden with the
options "uu.exit and "uu.fail" respectively.

When 'fx.wQuirks' is off, FX returns 0 when the connection has been
completed, and one when it should be retried. Reasons for retries could
be failed scripts, loss of carrier, fatal timeouts, etc. If multiple
connections are requested with -s all or -s any, the exit level reflects
the status of the last connection attempted. Note that no connections due
to no queued jobs is interpreted as successfull.

FX may abort with higher exit levels, typically two or three, because of
configuration or I/O errors. Examples are, invalid parameters, some file
errors, or other unexpected situation.

If you need to know the precise reason and connection exit status, examine
the STATUS file documented below.


VI.    STATUS files

The format of these files have been completely changed. They are used for
two purposes, status and statistics. The 'uutraff' program, available
from our server, decodes these files and build several types of reports.
The format of these files, which is in binary, is available upon request.
You will trash the accumalated statistics if you mix incompatibles Uucicos,
but nothing else would be damaged though.


VII.   SECURITY

If you only poll other hosts and you don't receive incoming calls,
security is not a major issue. But when you operate Uucico as the
gate for an uucp server, and specialy when run unattended, you should
take care of possible security holes.

Uucp is not a fully secure protocol, yet with correct configuration
it would be enough to satisfy your normal security needs.

Two major options control which kind of access Uucico grants to remote
calls. The upload and download permits entries specifies which directories
are available besides the spool. Leaving both enties blank, will deny
any _remote_ request for uploading or downloading outside the spool.

The second issue is how to inforce that each host will 'take' its own
traffic and not other's one. Uucico by itself has now way to verify
if the remote host is the one it claims it is. This situation arises
because dial-in login is performed by other software, not by uucico.
If one valid uucp user enters the server with its own login name and
password, it may impersonate other system by using a different uucpname.

The solution has two steps. One is to link both pieces of software. The
front-end program must tell uucico the login name he verified with password.
The second step is to build a table that relate each login name to the
corresponding uucpname (or host).

For the first step, FX accepts the -u parameter that specifies the user
login name: "uucico -r0 -u <login_name>". If you are using waffle.exe
as your front-end program, use the %A variable.

The user name vs. uucpname table is done in the 'permits' file. For _each_
on of the host in 'systems' add an entry as the following one:

laser     /account=ulaser

Where 'laser' is the uucpname and 'ulaser' the login name. When FX
receives a call from a system that call itself 'laser', it will scan
for a 'permits' entry with the same name. Then, _if_ the -u parameter
has been passed on the command line _and_ there is an 'account' keyword
on the permit entry, FX will verify if they match. If they don't access
will not be granted and the connection will be rejected.

Notes:

   Don't use the -p parameter. This will force FX to use a specific
   'permits' entry and will disable the autolookup.

   The login name and password in the 'systems' file are not used in
   dial-in calls. They are the ones for accessing the remote host when
   _you_ call him, and not viceversa.

   There are other options in 'permits' that may be usefull for safety
   and security measures.


VIII.  LIMITS AND MEMORY USAGE

There is no formal limit for the number of sytems, scripts, dialers
and permits. We have been running a host with over 200 uucp accounts.

The routines that read the configuration files have a finit limited
buffer. But using line continuation, there is no formal limit to the
total length.

FX doesn't requiere large amounts of memory. The exact number of bytes
depend on many parameters, and obviouslly also slightly change among
releases. The bare minimum is around the 80 kilobytes. But FX will
never use more than 150 kb. There is not much point to have more that
200 kb free before running this FX uucico release.


IX.    CUSTOM INTERFACES WITH FX UUCICO

We strongly recommend you use Uux for spooling jobs. FX Uux is rather small
and fast, the overhead is very little in comparison with the full compatibi-
lity you gain.

Uucico scans the spool for workfiles. Each known host has a personal
directory under <spool>, both outgoing and incoming jobs are placed
here. All outgoing jobs have a workfile with precise instructions for
Uucico. They are in ASCII text and have a conventional extension of 'CMD'.
Empty workfiles are allowed and they serve the purpose of forcing a poll
to a particular host. Each line in the workfile represent a single file
transaction, normally to send a data file to the remote host.

Most jobs normally have one or more data files associated. Lines on the
workfiles point to the neccessary data files. In many cases, one of the
data file is actually an execution file, to be intrepreted by the remote
host uucp (uuxqt program). FX Uucico supports 'E'xecution requests, they
avoid the transmission of the execution file. Incoming execution commands
are automatically converted to the standard format. Outgoing ones are
processed differently between hosts that support Exec request and those
who not. When the remote uucico doesn't support them, FX transforms the
request to traditional 'S' commands on the fly. Everything is handled
transparently and automatically, no external intervention is needed.
Workfiles with Execution requests have a different format, see the the FX
Uucp documentation.


Those that write programs that parse the logs created by Uucico, should
take special consideration to achieve maximum compatibility in future
releases. Try to allow as many changes as possible, many improvements in
the logging were not implemented because they breaked third party utilities.

For example if you parse a time field, let your code handle different
compatible formats like 20:13 and 20:13.45 . Do not assume a fixed amount
of spaces between tokens, perform string comparison without regarding case,
etc.

All files you don't modify should be accessed in read only mode with
deny none or deny write mode. Do not keep locks for extended periods of
time.

Incoming jobs are munged. Munging is the process of converting those Unix
filenames (D.laserC0123), to DOS conventions (0C01234.D). The munging
algorythm is documented with C source code in a small archive, fxmunge.zip,
available from our servers.